.TH IPERF 1 "APRIL 2008" NLANR/DAST "User Manuals"
.SH NAME
iperf \- perform network throughput tests
.SH SYNOPSIS
.B iperf -s [
.I options
.B ]

.B iperf -c
.I server
.B [
.I options
.B ]

.B iperf -u -s [
.I options
.B ]

.B iperf -u -c
.I server
.B [
.I options
.B ]
.SH DESCRIPTION
iperf is a tool for performing network throughput measurements.  It can test
either TCP or UDP throughput.  To perform an iperf test the user must
establish both a server (to discard traffic) and a client (to generate
traffic).
.SH "GENERAL OPTIONS"
.TP
.BR -b ", " --bandwidth " "
set the target bandwidth and optional standard devation per \fI<mean>\fR,\fI[<stdev>]\fR (See NOTES for suffixes)
.TP
.BR -e ", " --enhanced " "
Display enhanced output in reports otherwise use legacy report (ver 2.0.5) formatting (see notes)
.TP
.BR -f ", " --format " "
[abkmgBKMG]   format to report: adaptive, bits, Bytes, Kbits, Mbits, Gbits, KBytes, MBytes, GBytes (see NOTES for more)
.TP
.BR -h ", " --help " "
print a help synopsis
.TP
.BR -i ", " --interval " \fIn\fR"
pause \fIn\fR seconds between periodic bandwidth reports
.TP
.BR -l ", " --len " \fIn\fR[kmKM]"
set read/write buffer size (TCP) or length (UDP) to \fIn\fR (TCP default 128K, UDP default 1470)
.TP
.BR "    --l2checks "
perform layer 2 length checks on received UDP packets (requires systems that support packet sockets, e.g. Linux)
.TP
.BR -m ", " --print_mss " "
print TCP maximum segment size (MTU - TCP/IP header)
.TP
.BR -o ", " --output " \fIfilename\fR"
output the report or error message to this specified file
.TP
.BR -p ", " --port " \fIn\fR"
set server port to listen on/connect to to \fIn\fR (default 5001)
.TP
.BR -u ", " --udp " "
use UDP rather than TCP
.TP
.BR "    --udp-counters-64bit "
use 64 bit UDP sequence numbers
.TP
.BR -w ", " --window " \fIn\fR[kmKM]"
TCP window size (socket buffer size)
.TP
.BR -z ", " --realtime " "
Request realtime scheduler, if supported.
.TP
.BR -B ", " --bind " \fIhost\fR"
bind to \fIhost\fR, ip address or multicast address and optional port (see notes)
.TP
.BR -C ", " --compatibility " "
for use with older versions does not sent extra msgs
.TP
.BR -M ", " --mss " \fIn\fR"
set TCP maximum segment size (MTU - 40 bytes)
.TP
.BR -N ", " --nodelay " "
set TCP no delay, disabling Nagle's Algorithm
.TP
.BR -v ", " --version " "
print version information and quit
.TP
.BR -x ", " --reportexclude " [CDMSV]"
exclude C(connection) D(data) M(multicast) S(settings) V(server) reports
.TP
.BR -y ", " --reportstyle " C|c"
if set to C or c report results as CSV (comma separated values)
.SH "SERVER SPECIFIC OPTIONS"
.TP
.BR -b ", " --bandwidth " \fIn\fR[kmgKMG]"
set target read rate to \fIn\fR bits/sec. TCP only for the server.
.TP
.BR -s ", " --server " "
run in server mode
.TP
.BR "    --udp-histogram[="\fIbinwidth\fR[u],\fIbincount\fR,[\fIlowerci\fR],[\fIupperci\fR] "]"
output UDP latency histograms, bin width (default 1 millisecond, append u for microseconds,) bincount is total bins (default 1000), ci is confidence interval between 0-100% (default lower 5%, upper 95%)
.TP
.BR -B ", " --bind " \fIip\fR | \fIip\fR%\fIdevice\fR"
bind src ip addr and optional src device for receiving
.TP
.BR -D ", " --daemon " "
run the server as a daemon.  On Windows this will also install the IPerfService.
.TP
.BR -H ", " --ssm-host " \fIhost\fR"
Set the source host (ip addr) per SSM multicast, i.e. the S of the S,G
.TP
.BR -R ", " --remove " "
remove the IPerfService (Windows only).
.TP
.BR -U ", " --single_udp " "
run in single threaded UDP mode
.TP
.BR -V ", " --ipv6_domain " "
Enable IPv6 reception by setting the domain and socket to AF_INET6 (Can receive on both IPv4 and IPv6)
.SH "CLIENT SPECIFIC OPTIONS"
.TP
.BR -b ", " --bandwidth " \fIn\fR[kmgKMG] | \fIn\fRpps"
set target bandwidth to \fIn\fR bits/sec (default 1 Mbit/sec) or
\fIn\fR packets per sec.  This may be used with TCP or UDP.  For variable loads use format mean,standard deviation
.TP
.BR -c ", " --client " \fIhost\fR"
run in client mode, connecting to \fIhost\fR
.TP
.BR -d ", " --dualtest " "
Do a bidirectional test simultaneously
.TP
.BR "    --fq-rate n[kmgKMG]"
Set a rate to be used with fair-queueing based socket-level pacing, in bytes or bits per second. Only available on platforms supporting the SO_MAX_PACING_RATE socket option. (Note: Here the suffixes indicate bytes/sec or bits/sec per use of uppercase or lowercase, respectively)
.TP
.BR "    --incr-dstip"
increment the destination ip address when using the parallel (-P) option
.TP
.BR "    --ipg "\fIn\fR
set the interpacket gap to \fIn\fR (units of milliseconds) for packets within an isochronous frame (burst), requires --isochronous
.TP
.BR "    --isochronous[=" \fIfps\fR:\fImean\fR,\fIstdev\fR "]"
send isochronous traffic with frequency frames per second and load defined by mean and standard deviation using a log normal distribution, defaults to 60:20m,0.  (Note: Here the suffixes indicate bytes/sec or bits/sec per use of uppercase or lowercase, respectively)
.TP
.BR -n ", " --num " \fIn\fR[kmKM]"
number of bytes to transmit (instead of -t)
.TP
.BR -r ", " --tradeoff " "
Do a bidirectional test individually
.TP
.BR -t ", " --time " \fIn\fR"
time in seconds to listen for new traffic connections, receive traffic or transmit traffic (Defaults: transmit is 10 secs while listen and receive are indefinite)
.TP
.BR "    --trip-time "
request the server to report the total trip time, i.e from the client's 3WHS done to client's (fin, fin-ack or socket close) (requires synchronized clocks)
.TP
.BR "    --txstart-time "\fIn\fR.\fIn\fR
set the txstart-time to \fIn\fR.\fIn\fR using unix or epoch time format (supports nanonsecond resolution, e.g 1536014418.839992457)
.TP
.BR -B ", " --bind " \fIip\fR | \fIip\fR:\fIport\fR | \fIipv6 -V\fR | \fI[ipv6]\fR:\fIport -V\fR"
bind src ip addr and optional port as the source of traffic (see notes)
.TP
.BR -F ", " --fileinput " \fIname\fR"
input the data to be transmitted from a file
.TP
.BR -I ", " --stdin " "
input the data to be transmitted from stdin
.TP
.BR -L ", " --listenport " \fIn\fR"
port to recieve bidirectional tests back on
.TP
.BR -P ", " --parallel " \fIn\fR"
number of parallel client threads to run
.TP
.BR -R ", " --reverse " "
reverse the traffic flow after header exchange, useful for testing through firewalls
.TP
.BR -S ", " --tos " "
set the socket's IP_TOS (byte) field
.TP
.BR -T ", " --ttl " \fIn\fR"
time-to-live, for multicast (default 1)
.BR -V ", " --ipv6_domain " "
Set the domain to IPv6 (send packets over IPv6)
.TP
.BR -X ", " --peerdetect " "
run server version detection prior to traffic.
.TP
.BR -Z ", " --linux-congestion " \fIalgo\fR"
set TCP congestion control algorithm (Linux only)
.SH ENVIRONMENT
.TP
.BR TCP_WINDOW_SIZE
Controls the size of TCP buffers.
.SH NOTES
Some numeric options support format characters per '<value>\fIc\fR' (e.g. 10M) where the \fIc\fR format characters are k,m,g,K,M,G.  Lowercase format characters are 10^3 based and uppercase are 2^n based, e.g. 1k = 1000, 1K = 1024, 1m = 1,000,000 and 1M = 1,048,576
.TP
The -b option supports variable offered loads through the <mean>,<standard deviation> format, e.g. -b 100m,10m on the client.  The distribution used is log normal.  Similar for the isochronous option.
.TP
The -e or --enhanced latency output on the UDP servers assumes the clients' and servers' system clocks are synchronized.  Network Time Protocol (NTP) or Precision Time Protocol (PTP) are commonly used for this.  The reference clock(s) or oscillator's error will also affect the accuracy of UDP latency measurements.
.TP
The -B option affects the bind() system call.  This is typically used to bind to a particular IP address. Only packets destined to that IP address will be received while any transmitted packets will carry that IP address as their source. The bind() does not control anything about the routing of transmitted packets. So, for example, if the IP address of eth0 is used for -B and the routing table for the destination IP address (per -c) resolves the ouput interface to be eth1, then the host will send the packet out device eth1 with the source IP address of eth0.  To affect the physical output interface (e.g. dual homed systems) the host's routing table(s) need to be configured, e.g. configure policy routing per each -B source address.
.TP
The TCP connect time (or three way handshake) can be seen on the iperf client when the -e (--enhancedreports) option is set. Look for the ct=<value> in the connected message, e.g.in '[  3] local 192.168.1.4 port 48736 connected with 192.168.1.1 port 5001 \fB(ct=1.84 ms)\fR' shows the 3WHS took 1.84 milliseconds.
.TP
The network power (NetPwr) metric is \fBexperimental\fR.  It's a convenience function defined as throughput/delay.  For TCP, the delay is the sampled RTT times.  For UDP the delay is the end/end latency.  Don't confuse this with the physics definition of power (delta energy/delta time) but more of a measure of a desireable property divided by an undesireable property.  Also note, one must use -i interval with TCP to get this as that's what sets the RTT sampling rate.  The metric is scaled to assist with human readability.  (Note: if this metric goes beyond the experimental state we'll consider a supporting and RTT sampling rate independent of the -i interval.)
.SH DIAGNOSTICS
This section needs to be filled in.
.SH BUGS
See https://sourceforge.net/p/iperf2/tickets/
.SH AUTHORS
Iperf2, based from iperf (originally written by Mark Gates and Alex Warshavsky), has a goal of maintainence with some feature enhancement.
Other contributions from Ajay Tirumala, Jim Ferguson, Jon Dugan <jdugan at x1024 dot net>,
Feng Qin,
Kevin Gibbs,
John Estabrook <jestabro at ncsa.uiuc.edu>,
Andrew Gallatin <gallatin at gmail.com>,
Stephen Hemminger <shemminger at linux-foundation.org>,
Tim Auckland,
Robert J. McMahon <rjmcmahon at rjmcmahon.com>
.SH "SEE ALSO"
http://sourceforge.net/projects/iperf2/
